How to Make a Quarto Website

Author

Kline DuBose

Published

April 22, 2025

First, due credit where credit is due. The following document was heavily influenced by tutorials found on the Quarto website.

Additionally, this tutorial does not go over how to set up a GitHub page. Please refer to the Quickstart for GitHub Pages tutorial for help getting started hosting on GitHub pages.

Prep Work

First, I recommend making sure you have a current version of R, RStudio, and Quarto.

Quarto and RStudio have been created by Posit. Quarto is essentially an updated version of RMarkdown files that have some different capabilities than it’s predecessor. I would highly recommend looking into it. Posit has made numerous tutorials about the framework. It’s pretty cool.

Getting Started

Create a New Project

Starting to create a website is pretty easy. You simple have to create a new project in RStudio.

Click on the new project button in the top left of the RStudio IDE.
Select new project
Select the “Quarto Website” option

Create a new name for the directory. I host my website on GitHub Pages and follow the naming convention for that (i.e. kpdubose-website which is related to kpdubose.github.io)

Then click create project. This will create a new project with four files: _quarto.yml, about.qmd, index.qmd, and styles.css.

The New Files

Let’s dive briefly into the new files you can see.

quarto.yml

This file is like the yml header that for most .qmd files, but this affects to the whole website. It sets the default theme, default styles, title, navbar, etc… There are a lot of features that can be played with here, that we can dive into later, or can be looked up on the Quarto website.

You can change the theme from page to page (kind of like I did with this page on my website) by specifying a different theme on the individual pages. (Though this is a newer feature. Older versions of Quarto will not allow the themes to differ from page to page.)

about.qmd

This is one of the pages on the website. If you’re using this as a portfolio website, this can be the page about you! For the example code of how I set up my “About” page, please look at my Github file.

index.qmd

This is the home page for the website. As with the about page, additional information can be added and changed. I have the home page set up to show a list of links to different projects and other pages on the website. Some of these are not accessible via the navbar so it can be pretty helpful. You can even just use this page as your about you page. For an example of you I set up my index page, please click here.

styles.css

This is the styles.css page. You can assign html objects for the website here.

An Additional File

Add an .scss file

This file isn’t generated automatically, but it can be helpful to have for changing the theme of your website.

I like to call this file “custom.scss”. You can create this in RStudio by adding a new file and just calling it that.

You can use it to edit the website theme by specifying specific colors, specific fonts, background colors, etc… I edit this as needed, but most of the Quarto website themes. If you have questions about what a specific theme looks like, they can all be found here.

I copied my main website theme from the morph theme, but then made some changes to the *.scss file associated with it. For an example of this theme, please look here.

Let’s check it out

There are two important terminal commands to know when constructing your website.

The first is quarto preview. This is the general, let’s make sure everything is linked properly and working the way I was hoping it would.

The second command is quarto render. This command builds the website. It should be run before you upload the files to the cloud, or if you make any big changes to the themes of the website.

When you run the quarto preview command it should look something like this (assuming you haven’t made any changes).

But yeah. That’s the basics. You can play around with it. The next few sections cover my ramblings and different work arounds that I have found for problems that I have had. These can all be found by searching the internet, but I thought it might be helpful to keep some here.

Additional Thoughts and Examples

Different Quarto Formats

I’ve started to experiment with a few different formats for pages. I’m planning to keep a running list of formats I’ve gotten to integrate with the GitHub pages website properly and other tips and tricks for them.

Renders from a .qmd with no trouble:

html
pdf

Everything tells me it should work, but it hasn’t yet:

revealjs

Hosting on GitHub pages

If you plan to host on GitHub pages, there are a few tips.

The docs folder

In the _quarto.yml file you can specify an output directory with the output-dir option. While I think you can build the website by specifying the output-dir to really be anything, I prefer to build my website to a folder called docs and building the website from there, which I will detail in the next section. In the meantime, add this code to your _quarto.yml file:

project:
  type: website
  output-dir: docs

I push my entire project including all of my .qmd files and images I used in making my website, mainly for easy reference in this page of my website. When you quarto render it creates a few different files, including the “docs” directory if you have included the output-dir: docs option.

The “docs” folder should now contain all the files to make the website. When you push to GitHub, there is an option to build from a specific branch and folder. Make sure you are building from the docs folder.

If you aren’t using git commands to push and pull from the repository, you just have to upload the new docs folder after each render.

.nojekyll file

If you’re hosting on GitHub, you need to include a .nojekyll file. (For reasons better explained here)

You can include one by running the following line of cod in the command terminal

For Windows:

copy NUL .nojekyll

For Mac/Linux:

touch .nojekyll

The final push

In the command terminal, the following lines of code can be run to push to GitHub. This is after you’ve linked the depository to you project.

quarto render
git add docs
git commit -m "Publish site to docs/"
git push

Additionally, you can just render the website and upload the docs folder to the pages website.

How to structure a _quarto.yml

Below is the code I have used for my _quarto.yml. This has a brief explanation of each code chunk and what it does for the website.

This section defines the project type, and the output-directory. Since I host my website on GitHub, I have my output-directory set as docs, as explained above. The render option let’s you select which documents you would like to render to the website. “*.qmd” tells Quarto to render all .qmd files. “!tournament-announcements/” and “!resumes/” tells Quarto to not render any files found in this directory

project:
  type: website
  output-dir: docs
  render:
    - "*.qmd"
    - "!tournament-announcements/"
    - "!resumes/"

The next two section deal with the look of the website. This specific section defines the title of the website as “Kline DuBose” (fitting for a portfolio website) and then establishes the navbar at the top of the page. It sets it to the left and makes then links to pages I have made and set in the navbar. There are a lot of options for this, but googling website options makes it easy for you to look into it.

website:
  title: "Kline DuBose"
  navbar:
    left:
      - href: index.qmd
        text: Home
      - href: main_about.qmd
        text: About
      - href: main_projects.qmd
        text: Projects

This section sets up the footer for the entire website. Mine includes links with specific icons and different websites. As well as the address of my institution.

  page-footer:
    background: light
    left:
      - icon: twitter-x
        href: https://x.com/KlineDuBose
      - icon: github
        href: https://github.com/KPDuBose
      - icon: linkedin
        href: https://www.linkedin.com/in/kline-dubose/
      - icon: envelope
        href: mailto:kline.dubose@utah.edu
    right:
      - "295 Chipeta Way, 3rd Floor
         Salt Lake City, UT 84108
         United States"

This last section sets additional format information for the website.

format:
  html:
    theme: 
      - morph
      - custom.scss
    css: styles.css
    toc: true

Resume

You should be able to include your resume or CV on the website without too much trouble. I have a quarto document that I use to make sure it renders nicely and that I don’t make any mistakes with my poor Microsoft Word skills. Just make sure that you include a “.docx” or a ”.pdf” option in the render section of your _quarto.yml file. I haven’t played around with it a ton.

If you would like to see the files I’ve used to construct my CV, they can be found on my GitHub.

Icons

Finding the icons associated with the quarto projects. They can be found on the Quarto website under the Nav Options section, but that just redirects you to the Bootstrap icons website. Quarto uses the bootstrap framework, I think. I haven’t really delved into it, so don’t take my word for it.

404

You can also include an error page. Unless you’re doing something really fancy, you can just include a 404.qmd file. My 404.qmd is pretty basic, but it fits well with my theme. Here’s what it looks like when you find it.

If you’re doing something fancier, check out the website navigation tutorial

Making a Blog

A formatting option that you can include that renders pages as an index of other pages could be helpful. For an example of this, click here for the way my website incorporates it, here too see my raw .qmd file, or here for a detailed tutorial from Quarto.

When looking at the .qmd source file, we can see what the header looks like:

---
title: "Presentations and Tutorials"
listing: 
  contents: presentations
  type: grid
---

Let’s break this down a little bit.

title: just names the webpage
listing: tells us that we want to create a list of other pages that looks kinda pretty.
- contents: tells Quarto what folder to reference here. In this case I reference all .qmd files in my presentations folder. You can also reference specific files, as seen here.
- type: grid tells Quarto what style I want to use. Examples of other styles can be found here.

That’s it, for now

That should be enough information to help you get started. Quarto is a versatile tool, and they have a lot of tutorials to help one get profecient at using it.

Feel free to check out my GitHub project and let me know if you have any question.

Good luck out there!